Create a new category.

12 May 2026
8 Minutes to read
Contributors

Print
Share
Dark
Light

Create a new category.

Updated on 12 May 2026
8 Minutes to read
Contributors

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Post

/v3/projects/{project_id}/categories

Creates a new category within the specified project version. Requires UpdateCategories permission. The user_id field is required when using an M2M (machine-to-machine) token rather than a user token. Supports Markdown, WYSIWYG, and Block content types. If slug is omitted it is auto-generated from the category name; duplicate slugs will cause a 422 validation error.

Security

OAuth

All V3 endpoints require a Bearer token. Generate tokens in the Document360 portal under Settings > API Tokens. Tokens are project-scoped, require the customerApi scope, and do not expire by default. Tokens can be revoked at any time from the portal. Include the token in every request: Authorization: Bearer <your-token>. Alternatively, use the Authorize button below to sign in via OAuth2 Authorization Code flow with PKCE.

FlowAuthorization Code

Authorization URLhttps://identity.document360.net/connect/authorize

Token URLhttps://identity.document360.net/connect/token

Scopes:

customerApiDocument360 Customer API

Path parameters

project_id

string (uuid) Required

The unique identifier of the project. Retrieve project IDs from GET /v3/projects.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

Body parameters

Category creation details.

Create a top-level category

Creates a new folder-type category at the root level of a project version.

{
  "name": "Getting Started",
  "project_version_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
  "order": 0,
  "parent_category_id": null,
  "content": null,
  "category_type": 0,
  "user_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "content_type": 0,
  "slug": null
}

Create a nested category with content

Creates a page-type category nested under an existing parent category.

{
  "name": "Installation Guide",
  "project_version_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
  "order": 1,
  "parent_category_id": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
  "content": "# Installation\nFollow these steps to install the product.",
  "category_type": 1,
  "user_id": null,
  "content_type": 0,
  "slug": "installation-guide"
}

object

Request to create a new category.

name

string Required

Name of the category.

Min length1

project_version_id

string Required

Project version to create the category in. Retrieve version IDs from GET /v3/projects/{projectId}/project-versions.

Min length1

order

integer (int32)

Sort order of the category within its parent.

parent_category_id

string | null

Parent category identifier for nesting. Retrieve category IDs from GET /v3/projects/{projectId}/categories. Omit for a top-level category.

content

string | null

Initial content for the category.

category_type

string

Type of the category. Possible values: 0 = Folder, 1 = Page, 2 = Index.

Valid values[ "folder", "page", "index" ]

user_id

string | null

User ID performing the creation. Required for API token (M2M) authentication. When using a user access token (OAuth), this field is ignored — the user ID is resolved from the token. Retrieve user IDs from GET /v3/projects/{projectId}/users.

content_type

string | null

Content format type. Possible values: 0 = Markdown, 1 = Wysiwyg (rich text), 2 = Block.

Valid values[ "markdown", "wysiwyg", "block" ]

Responses

201

Category created successfully.

Headers

Location

string

URL of the newly created resource.

Category created successfully

Returns the newly created category with its assigned identifier and order.

{
  "data": {
    "id": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
    "name": "Troubleshooting",
    "order": 3,
    "icon": "icon-wrench",
    "created_at": null,
    "modified_at": null
  },
  "success": true,
  "request_id": "req_abc123def456",
  "errors": null,
  "warnings": null
}

Expand All

object

Generic API response wrapper containing typed data.

data

object

Response data payload.

string (uuid) | null

Unique identifier of the category.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

name

string | null

Name of the category.

order

integer (int32)

Sort order within the parent category.

icon

string | null

Icon identifier for the category.

created_at

string (date-time) | null

Date and time the category was created.

modified_at

string (date-time) | null

Date and time the category was last modified.

success

boolean

Whether the API request was successful.

request_id

string

Unique identifier for request tracing and correlation.

Min length1

errors

Array of object (ApiError) | null

List of errors if the request failed.

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

List of non-fatal warnings from the request.

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

400

The request body is malformed or contains invalid JSON.

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

401

Authentication token is missing or invalid.

Headers

WWW-Authenticate

string

Indicates the authentication scheme required. Returns `Bearer` with optional `error` and `error_description` parameters per RFC 6750.

Missing or invalid token

Authentication token is missing or invalid.

{
  "type": "https://developer.document360.com/errors/unauthorized",
  "title": "Unauthorized.",
  "status": 401,
  "detail": "The authentication token is missing or has expired.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "Bearer token is missing or invalid.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

422

Validation failed.

Validation failed

The request body contains invalid data.

{
  "type": "https://developer.document360.com/errors/validation-error",
  "title": "Unprocessable Entity.",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "This field is required.",
      "field": "title",
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

429

Rate limit exceeded. Retry after the duration specified in the Retry-After header.

Headers

Retry-After

integer

Number of seconds to wait before retrying the request. Use exponential backoff with jitter for optimal retry behavior.

X-RateLimit-Limit

integer

The maximum number of requests allowed in the current time window. Limits are applied per API token per project.

X-RateLimit-Remaining

integer

The number of requests remaining in the current time window. When this reaches 0, subsequent requests will receive a 429 response.

X-RateLimit-Reset

integer

The UTC epoch timestamp (in seconds) when the current rate limit window resets.

Rate limit exceeded

Rate limit exceeded.

{
  "type": "https://developer.document360.com/errors/too-many-requests",
  "title": "Too Many Requests.",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "TOO_MANY_REQUESTS",
      "message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

500

An unexpected server error occurred.

Unexpected server error

Unexpected server error.

{
  "type": "https://developer.document360.com/errors/internal-error",
  "title": "Internal Server Error.",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "INTERNAL_SERVER_ERROR",
      "message": "An unexpected error occurred.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

Was this article helpful?

What's Next

Bulk create categories.